Skip to content

Recent Components page, RSS feed #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 21, 2016
Merged

Recent Components page, RSS feed #131

merged 4 commits into from
Dec 21, 2016

Conversation

sebastienbarre
Copy link
Contributor

Hi folks.
This PR adds a new "Recent Components" page, and "Recent Components" RSS feed.

tachyons_-_recent_components

subscribe_to_this_feed

A couple more, small, build scripts were added -- check build.js

co(function* generator() {
  yield componentsBuildList(options);        // <- builds temporary components list (JSON)
  yield componentsBuildIndex(options);       // <- builds index pages (by category & most recent)
  yield componentsBuildRSS(options);         // <- builds RSS feed
  yield componentsBuildPages(options);       // <- comment to skip building pages
  yield componentsBuildScreenshots(options); // <- comment to skip building screenshots
}).then(() => {
  • The temporary file that lists all components is now built by componentsBuildList,
  • The index pages are built componentsBuildIndex,
  • The RSS feed is built by componentsBuildRSS,
  • The rest is unchanged.

Note that componentsBuildList now uses the Git api (via nodegit) to find when a component was first committed to the repo. Took me some gitter/slack back and forth with the nodegit people, but I think this is robust to renaming and moving the component around. This introduces a new creationTime key in the component list (the temporary JSON file), which is leveraged later on. I also store a new author key, which is used in the RSS feed. Note that all this querying of the repo slows down this step, but it shouldn't be too bad (about 5 seconds on my laptop for all of the components).

The index pages still use the same template file, but new options allow for more flexibility. The list of index pages to build is in options.components.index:

  components: {
    index: {                                       // list index pages to build
      byCategory: {                                // components by category
        title: 'Components',
        path: 'components/index.html',             // target location of index by category
        sortAllBy: [['src'], ['asc']],             // sort by file location will do
        limitAll: false,                           // use all components
        createSectionsBy: 'category',              // create a section for each category
        showSectionsTOC: true,                     // show Table of Contents (e.g. categories)
      },

The byCategory key above describes the previously existing index page, the one listing all components by category. These options can be passed to a small function in components-build-sections that return a new list of components organized by sections. In the above example,

  • the list of components is first sorted by the src attribute (the path on disk),
  • all of the components are taken into account (limitAll is false),
  • sections are created by looking at the category key on each component,
  • there is a Table of Contents.

Now here is another index, and that's all it takes to describe the new "Recent Components" page:

      mostRecent: {                                // most recent components
        title: 'Recent Components',
        path: 'components/recent.html',            // target location of recent index
        sortAllBy: [['creationTime'], ['desc']],   // sort by most recent component first
        limitAll: 50,                              // use the 50 most recent ones
        createSectionsBy: creationTimeToYMD,       // group by day
        prettifySection: v => moment(v).format('LL'), // display as day
        showSectionsTOC: false,                    // no need for Table of Contents
      },
  • the list of components is first sorted by the creationTime attribute, most recent first,
  • only 50 components are on that page -- set to false if you prefer to list all of them,
  • sections could have been created using the creationTime key, but I thought it looked better when grouping all components created the same day together. The creationTimeToYMD callback takes a component and return whatever value you want to group components by (e.g. the section) -- in this case it converts the component creation time (milliseconds) to a YYYY-MM-DD format. Change it back to 'creationTime' if you'd prefer a section for each component.
  • prettifySection is a callback that will format the section for display on the page. Here, it converts the YYYY-MM-DD value to something more human-readable. Remove that property altogether if you end up switching createSectionsBy back to 'creationTime', since formatting the creationTime property is already handled by the options.components.prettify.creationTime callback.
  • I'm hiding the Table of Contents, which would only be a list of dates, didn't find it very useful.

The options.components.rss object should be self-explanatory:

    rss: {                                         // RSS feed
      title: 'Tachyons Recent Components',
      categories: ['CSS', 'Functional CSS'],       // Categories this feed belongs to
      ttl: 60,                                      // Number of mins feed can be cached
      path: 'components/rss.xml',                  // target location of feed (sync head.html)
      count: 20,                                   // how many in feed
    },

I decided to only include 20 of the most recent components in that feed, that's a common value for feeds; feel free to customize.

Building a RSS feed that properly features the component screenshot was... tricky. I tried RSS enclosures, RSS custom elements -- no dice. I ended up looking at how http://unsplash.com does it. It seems to work fine. For RSS auto-discovery I added this to the templates/head.html:

<link rel="alternate" type="application/rss+xml" title="RSS Feed for Tachyons Recent Components" href="/components/rss.xml" />

This should hopefully let you put any pages from http://tachyons.io inside a RSS feed reader, and get the RSS feed directly.

What I leave up to you:

  • the new "Recent Components" page (aka components/recent.html) is not referenced from any other page right now. Feel free to add a link to it from the header? Making it look good is not my area of expertise :)
  • same for http://tachyons.io/components/rss.xml -- RSS auto-discovery should work, but feel free to explicitly mention the feed on the home page.
  • once this is up online, let's test the feed together -- I'll subscribe to it and hopefully you can add a component later on. If/when I see it in my reader I'll let you know that it all worked nicely.

Let me know if you have any questions, feedback, etc.

Copy link
Member

@johno johno left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stellar work again @sebastienbarre! 🚀 ✨ 💖

@mrmrs mrmrs merged commit ff2ffe2 into tachyons-css:master Dec 21, 2016
@mrmrs
Copy link
Member

mrmrs commented Dec 21, 2016

This is really amazing work.

@sebastienbarre
Copy link
Contributor Author

Thanks guys. I'll keep an eye open, and once the RSS feed is up I'll let you know if it works as expected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants